Skip to content

feat: add Compass catalog manifests for all agentic packs#133

Draft
r2dedios wants to merge 20 commits into
RHEcosystemAppEng:mainfrom
r2dedios:compass-skill-manifests
Draft

feat: add Compass catalog manifests for all agentic packs#133
r2dedios wants to merge 20 commits into
RHEcosystemAppEng:mainfrom
r2dedios:compass-skill-manifests

Conversation

@r2dedios

@r2dedios r2dedios commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

Summary

Register the entire agentic-plugins repository in Red Hat Compass (Backstage) with a complete hierarchy of catalog manifests covering all 7 agentic packs, 75 skills, and 7 MCP servers.

Architecture

Location (root catalog-info.yaml)
│
├── System (agentic-plugins) ── models the whole repository
│
├── Location (ocp-admin)       → AiResource(plugin) + 7 skills
├── Location (rh-sre)          → AiResource(plugin) + 13 skills
├── Location (rh-virt)         → AiResource(plugin) + 10 skills
├── Location (rh-developer)    → AiResource(plugin) + 17 skills
├── Location (rh-basic)        → AiResource(plugin) + 6 skills
├── Location (rh-ai-engineer)  → AiResource(plugin) + 11 skills
├── Location (rh-automation)   → AiResource(plugin) + 11 skills
│
└── Location (mcps)
    └── MCPServer ×7 (owned by us)

Entity inventory

Kind spec.type Count Description
Location 9 1 root + 7 packs + 1 mcps
System 1 agentic-plugins (repo-level grouping)
AiResource plugin 7 One per agentic pack
AiResource skill 75 Individual skills across all packs
MCPServer local/remote 7 Owned MCP servers
Total 99

Relationships

  • AiResource(plugin)partOfSystem(agentic-plugins) via spec.system
  • AiResource(skill)dependsOnAiResource(plugin) of its parent pack
  • AiResource(skill)dependsOnMCPServer (when the skill uses MCP tools)
  • AiResource(plugin)dependsOnMCPServer (pack-level MCP dependencies)
  • MCPServerpartOfSystem(agentic-plugins) via spec.system
  • All entities → ownedBygroup:redhat/ecosystem-appeng

Canonical MCP server reuse

Two MCP servers already registered in Compass by their upstream teams are not duplicated — skills reference the canonical entities directly:

Canonical entity Namespace Owner
red-hat-lightspeed-mcp-server redhat rh-lightspeed-mcp
security-mcp-server redhat lightforge-mcp-dev

Key design decisions

  • AiResource over System for packs: Packs are modeled as AiResource(type: plugin) instead of System, consistent with Backstage AI resource modeling and supporting many-to-many skill↔MCP dependencies
  • Location delegation: Root Location only references child Locations (one per pack + one for MCPs). Each child Location indexes its own entities. No direct leaf references from root
  • Namespace per pack: Each pack uses its own namespace (e.g., rh-sre, ocp-admin). MCP servers use agentic-plugins namespace
  • Reuse canonical MCPs: Per Compass team guidance, existing MCP servers are referenced rather than re-registered

Test plan

  • All manifests validated against Compass validate-entity API
  • Entities registered and visible in Compass catalog
  • Entity relationships verified (dependsOn, partOf, ownedBy)
  • Canonical MCP server references resolve correctly
  • Verify System page shows contained entities (known Compass limitation for custom kinds)

r2dedios and others added 19 commits July 3, 2026 15:46
Add catalog-info.yaml manifests to register the repository and ocp-admin
agentic pack in Red Hat Compass (Backstage). Includes:

- Root Location pointing to all agentic packs
- ocp-admin pack Location aggregating skills and MCP servers
- 7 AiResource entities for skills (cluster-creator, cluster-inventory,
  cluster-report, container-cve-validator, coreos-cve-validator,
  cve-recon, image-inspect)
- 3 MCPServer entities (openshift-self-managed, openshift-ocm-managed,
  openshift-administration)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add 19 centralized MCP server manifests in ./mcps/ (flat structure)
  with deduplication by functional variant for shared images
- Add 68 skill (AiResource) manifests across 6 new packs:
  rh-sre (13), rh-virt (10), rh-developer (17), rh-basic (6),
  rh-ai-engineer (11), rh-automation (11)
- Add pack Location manifests for rh-sre, rh-virt, rh-developer,
  rh-basic, rh-ai-engineer, rh-automation
- Update root Location to reference all 7 packs + 19 MCPs
- Update ocp-admin Location: remove MCP targets, add labels
- Update ocp-admin skill dependsOn refs to use default namespace
- Remove old ocp-admin/mcps/ catalog-info.yaml files
- Add domain-prefixed labels on all Locations:
  agentic-plugins.redhat.com/version and
  agentic-plugins.redhat.com/repo
Create a Domain entity (agentic-plugins) as the top-level parent and
7 System entities (one per pack) to provide rich grouping pages in
Compass. Skills already reference their pack System via spec.system,
so Backstage will auto-generate hasPart relations once these exist.
Merge 19 MCP manifests into 9 by grouping variants that share the
same container image or server technology:
- 4 openshift-mcp-server variants → openshift-mcp-server
- 2 assisted-service-mcp variants → assisted-installer
- 2 lightspeed variants → red-hat-lightspeed
- 6 AAP endpoint variants → ansible-automation-platform
- 5 unique MCPs unchanged

Update all 75 skill dependsOn references and deduplicate where a
skill previously referenced multiple variants of the same MCP.
Domain kind is not allowed for GitHub-based Location registration
in Compass. Remove domain.yaml target and domain references from
all System manifests to unblock registration.
Add backstage.io/techdocs-ref annotation to each pack's system.yaml
pointing to the pack README.md on GitHub main branch.
Add dedicated namespace to all 9 MCPServer manifests and update
all 71 skill dependsOn references accordingly.
…tions

- Create System entity for shared MCPs (rh-agentic-plugins-mcps)
- Add spec.system to all 9 MCPServer manifests
- Add spec.dependsOn to 7 pack Systems linking to their MCPs
- Add agentic.redhat.com/* annotations to all pack Locations and Systems
- Fix repo label from "redhat-agentic-plugins" to "agentic-plugins"
- Remove domain.yaml (Compass rejects Domain from GitHub Locations)
Point each MCPServer to its upstream repo README:
- openshift-mcp-server → openshift/openshift-mcp-server
- assisted-installer → openshift-assisted/assisted-service-mcp
- red-hat-lightspeed → RedHatInsights/insights-mcp
- ansible-automation-platform → ansible/aap-mcp-server
- ai-observability → rh-ai-quickstart/ai-observability-summarizer
- rhoai → opendatahub-io/rhoai-mcp
- podman → manusa/podman-mcp-server
- github → github/github-mcp-server

red-hat-security skipped (no public repo, hosted service).
Add airesource dependsOn entries for orchestration skills that directly
invoke other skills via the Skill tool. Covers 37 dependencies across
8 skills in rh-sre, rh-developer, rh-automation, and rh-ai-engineer.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
TechDocs builder expects mkdocs.yml + docs/ in the target repo, but our
techdocs-ref URLs pointed to bare README.md files causing ENOENT errors.
Move upstream MCP repo URLs to metadata.links instead, where they render
as navigable links without triggering the builder.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace kind: System with kind: AiResource (type: plugin) for all 7
agentic packs. Rename system.yaml to <pack>-plugin.yaml. Add disciplines,
categories, agents, and lifecycle fields to each pack manifest.
Remove spec.system from all 75 skill catalog-info.yaml files and add
airesource:<pack>/<pack> to spec.dependsOn instead. Also update MCP
server references to use agentic-plugins namespace.
Add root System entity (agentic-plugins). Remove mcps/system.yaml and
consolidate all entities under the single system. Create mcps Location,
add plugin targets to pack Locations, and simplify root Location to
delegate through pack and MCP Locations only.
Document entity kinds, Location hierarchy, entity relationships,
namespaces, reference formats, and workflows for adding new skills
and packs with their Compass manifests.
Backstage resolves unqualified spec.system references relative to the
entity's own namespace. Since the System entity is in the default
namespace but plugins and MCPs use their own namespaces, the partOf
relation was not resolving. Use default/agentic-plugins to fix.
Compass does not auto-generate hasPart inverse relations for custom
kinds (AiResource, MCPServer). Declare them explicitly so the System
page shows its contained plugins and MCP servers.
Remove duplicate MCPServer entities for Red Hat Lightspeed and Red Hat
Security, replacing dependsOn references with their canonical versions
already registered in Compass by their respective teams:

- mcpserver:agentic-plugins/red-hat-lightspeed → mcpserver:redhat/red-hat-lightspeed-mcp-server
- mcpserver:agentic-plugins/red-hat-security → mcpserver:redhat/security-mcp-server

Reduces our registered MCP servers from 9 to 7.
@r2dedios r2dedios changed the title feat: add Compass catalog manifests for ocp-admin pack feat: add Compass catalog manifests for all agentic packs Jul 10, 2026
Update spec.owner across all 90 Compass manifests from
group:redhat/ecosystem-appeng to group:redhat/ai5-marketplace.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant